package cn.mujiankeji.mbrowser.功能.下载

import cn.mujiankeji.mbrowser.功能.下载.模型.下载任务
import kotlinx.coroutines.flow.Flow

interface 下载管理器接口 {

    /**
     * 根据提供的URL和可选参数，请求一个新的下载任务。
     * @param url 下载地址
     * @param 文件名 可选，如果为空，则尝试从URL或Content-Disposition生成
     * @param 目标路径 可选，如果为空，则使用默认下载路径
     * @param 请求头 可选，自定义HTTP请求头
     * @param userAgent 可选，自定义User-Agent
     * @return 返回创建的下载任务的ID
     */
    suspend fun 请求新下载(
        url: String,
        文件名: String,
        目标路径: String,
        请求头: Map<String, String>? = null,
        userAgent: String? = null
        // 可以根据需要添加更多参数，如 下载类型提示，优先级等
    ): String? // 返回任务ID，如果创建失败则返回null

    /**
     * 暂停一个正在进行或等待中的下载任务。
     * @param 任务Id 要暂停的任务ID
     */
    suspend fun 暂停下载(任务Id: String)

    /**
     * 恢复一个已暂停的下载任务。
     * @param 任务Id 要恢复的任务ID
     */
    suspend fun 恢复下载(任务Id: String)

    /**
     * 取消一个下载任务，并尝试删除已下载的部分文件。
     * @param 任务Id 要取消的任务ID
     */
    suspend fun 取消下载(任务Id: String)

    /**
     * 根据ID获取一个下载任务的实时状态 Flow。
     * @param 任务Id 任务ID
     * @return Flow<下载任务?>
     */
    fun 获取下载任务状态Flow(任务Id: String): Flow<下载任务?>

    /**
     * 获取所有下载任务的列表 Flow。
     */
    fun 获取所有下载任务Flow(): Flow<List<下载任务>>

    /**
     * 获取所有活动（正在下载、等待中、已暂停）下载任务的列表 Flow。
     */
    fun 获取活动下载任务Flow(): Flow<List<下载任务>>


    /**
     * 获取所有已完成下载任务的列表 Flow。
     */
    fun 获取已完成下载任务Flow(): Flow<List<下载任务>>


    /**
     * 根据ID删除一个下载任务记录（通常用于已完成或已取消的任务）。
     * @param 任务Id
     * @param 同时删除文件 是否同时删除磁盘上的文件
     */
    suspend fun 删除下载记录(任务Id: String, 同时删除文件: Boolean = false)

    /**
     * 清空所有已完成的下载记录。
     * @param 同时删除文件 是否同时删除磁盘上的文件
     */
    suspend fun 清空已完成下载记录(同时删除文件: Boolean = false)

    // TODO: 添加更多管理功能，例如：
    // - 重试下载(任务Id: String)
    // - 获取下载队列信息
    // - 修改任务优先级等
} 